Creating new docly files

1. What you'll see

   An AI coding agent or script creates a new .docly file from outside the Docly UI. Either the document does not open in Docly, or it renders as nothing. The instinct is to treat the filename as spent and start again under a different name.

2. What's actually happening

   The docly CLI creates a document in one of two ways: clone the destination folder, write the file into the working copy and push it — or, for a single document, run docly put <folder path>/<name>.docly <file> --create. Either way the document is sent in a single request, so there is no window in which the server sees a partial file, and a push gives you a status list and a diff before anything is public.

   The server reads the Schema string from the envelope and binds the document to that schema; push has no schema flag. Measured 2026-09-04 against a live site: a pushed document has its Guid assigned and its Created and Modified stamped by the server, and Tags supplied in the envelope survive (they come back reordered, because they go through the database rather than being echoed from the file).

   A failed write does not burn the filename. Correct the JSON and write the same path again. A Schema value naming a schema that does not exist is not reported as an error: the document registers and keeps that string verbatim - there is no fallback to a generic upload - so it binds to nothing until the same path is written again with the correct schema name.

   So the reason to get the JSON right is that a document which fails to parse is useless, not that the name is spent.

3. What to do

   Create the document with docly put <folder path>/<name>.docly <file> --create, or write it into a working copy and push it. Validate that the JSON parses first - that is the only thing standing between you and a registered document.

   Minimum file envelope (regardless of schema):

   {
     "Document": { /* fields defined by your target schema */ },
     "EmbeddedFiles": [],
     "Schema": "<schema-name>",
     "Tags": [],
     "Modified": "2026-05-15T12:00:00.0000000+02:00",
     "Created": "2026-05-15T12:00:00.0000000+02:00"
   }

   The server assigns Guid and stamps Modified and Created with real timestamps on successful registration - placeholders are fine. ROWIDs inside form chapters are standard UUIDs with dashes; Docly generates them on save, but supplying fresh ones in a programmatically-built file is harmless.

   Structural traps that break a document (none of them burn the filename - fix and rewrite the same path):

   • A Schema value that does not name a real schema. The document registers with that literal string and therefore binds to nothing and renders as nothing.
   • Field names in Document not matching the schema's form fields (case-sensitive). Unlisted fields are dropped silently.
   • Enum values stored as user-facing labels instead of internal values (e.g. "By design" instead of "ByDesign"). Internal values come from the schema's Options[].Value, not Options[].Label.
   • Form Chapters expected to nest as sub-objects - they flatten. Fields inside a Chapter sit alongside the other Document properties, with one Expand boolean and one ROWID UUID per Chapter added.
   • Radio-group fields missing the FieldName__docly_radiogroup duplicate next to FieldName; both carry the same internal value.
   • Rich-text fields written as markdown - they are HTML strings, so escape " as \" inside the JSON.
   • Hand-rolling the count fields (OKCount, TotalCount, etc.). Docly maintains these on form save; start at "0" or copy from an existing instance.

   Writing over an existing document can replace it. If the content you write does not parse as the document’s type, the server stores it as a different type, which deletes the document and creates a new one with a new id — shares, publications and links to the old id are lost. docly push refuses such writes unless you pass --allow-replace.

   Verify registration by reading the document back and parsing it:

   • A Guid is present, assigned by Docly.
   • Created and Modified carry the server’s timestamps, not your placeholders.

   If the document did not register, correct the JSON and write the same path again.

   For the full reference, see Editing Docly documents programmatically. For the rest of the CLI workflow, see How an AI agent should use the docly CLI.

Last reviewed 04 Sep 2026